rbm_config(7)
=============

NAME
----
rbm_config - The rbm configuration

DESCRIPTION
-----------

All configuration options can be defined in 5 different places :

- in the main configuration in your working directory (+rbm.conf+)

- in the local configuration in your working directory (+rbm.local.conf+)

- in the global system configuration (+/etc/rbm.conf+)

- in a project configuration

- with a command line option

The option values are used with the following priority order :

- command line options

- project config for matching step and target

- project config for matching step

- project config for matching target

- project config

- local config for matching step and target

- local config for matching step

- local config for matching target

- local config

- workspace config for matching step and target

- workspace config for matching step

- workspace config for matching target

- workspace config

- system config for matching step and target

- system config for matching step

- system config for matching target

- system config

- default config

- undefined

The system configuration is by default located at +/etc/rbm.conf+, or
the path defined in the +sysconf_file+ option. If the path does not
exists, it is ignored. This is where you will put configuration only
relevant to your local use of rbm.

The main configuration file is +rbm.conf+, in YAML format. It can be
located anywhere on your filesystem, but you will need to run the
*rbm* commands from the same directory, or one of its subdirectories.
This is where you will put configuration relevant to all projects under
this working directory. All relative paths used in the configuration
are relative from the +rbm.conf+ location.

The local configuration file is +rbm.local.conf+ (or the file defined
by the +localconf_file+ option), in the same directory as the +rbm.conf+
file. If the file does not exists, it is ignored. The +rbm.local.conf+
file is used to override some options from +rbm.conf+ relevent to your
local setup, whithout modifying the +rbm.conf+ file which is usually
maintained in a VCS.

An example +rbm.conf+ file will look like this :

----
projects_dir: projects
compress_tar: xz
----

The +projects_dir+ option define the path to the directory containing
the projects definitions.

Adding a new project is done by creating a directory with the name of
the project inside the +projects_dir+ directory, and adding a +config+
file in this new directory. The +config+ file contains the configuration
for the project. At the minimum it should contain the +git_url+
configuration, and any other configuration option you want to set for
this project.

OPTIONS
-------

The following configuration options are available :

sysconf_file::
        The path to an optional system configuration file. The default
        is +/etc/rbm.conf+. This can also be set with the --sysconf-file
        command line parameter.

localconf_file::
        The path to an optional local configuration file. The default
        is +rbm.local.conf+. If the path is relative, it is relative to
        the directory where the +rbm.conf+ file is located. This can
        also be set with the --localconf-file command line parameter.

projects_dir::
        The directory containing the projects definitions. The default
        value is +projects+.

git_clone_dir::
        The directory used to store clones of git repositories. The
        default value is +git_clones+.

hg_clone_dir::
        The directory used to store clones of mercurial repositories.
        The default value is +hg_clones+.

hg_opt::
        This option contains options that should be passed on the
        mercurial command line. This can for instance be useful if you
        want to use the --config option to enable some mercurial plugins.

tmp_dir::
        The directory used to create temporary directories and files.
        This is the directory where builds will be done, so you want to
        use a directory on a fast device, with enough space available.
        This directory will contains some scripts that will be executed,
        so it should not be on a partition mounted as noexec.

rbm_tmp_dir::
        A directory created inside +tmp_dir+ using +File::Temp+, that
        you can use to store temporary files. This directory is removed
        automatically when rbm exits. When running scripts, the TMPDIR
        environment variable is also set to this directory.

rbmdir::
        The directory where the rbm script is located.

output_dir::
        The directory where output files (tarballs, spec files or
        packages) are created. The default value is +out+.

build_log::
        The file where the build logs will be written. If the value is `-` (the
        default), the logs will be output on stdout and stderr.

build_log_append::
        If you set to +build_log_append+ to 0, the log file (defined in
        +build_log+) will be cleaned when starting a new build. The
        default is 1.

fetch::
        The value should be 0 or 1, depending on whether the commits
        from the remote git or hg repository should be fetched
        automatically. If the value is +if_needed+, the git or hg
        repository is fetched only if the selected commit cannot be
        found in the local clone. The default is +if_needed+.

ENV::
        This option, defined in the workspace config, is a hash
        containing the environment variables that will be defined
        when rbm is starting. This is useful for defining variables
        that can affect how the templates are processed (for instance
        the +TZ+ variable if dates are used).

include::options_tar.asc[]

arch::
        The architecture, as returned by 'uname -m'.

version::
        Version number of the software. This is used to create the
        tarball, and as the package version number.

distribution::
        The name of the distribution for which you wish to build a package.
        The syntax is +distribution-release+. This value is used by the
        +lsb_release+ option.

lsb_release::
        A hash containing +id+ (name of the distribution), +codename+
        and +release+. This option is useful in template to do different
        things for different distributions. By default, the output of
        the lsb_release command will be used if available. If the
        +distribution+ option is defined, it will be used instead to
        for the +id+ and +release+ (+codename+ will be undefined).

target::
        The target for which you want to build. This is usually set on
        command line. See link:rbm_targets.html[rbm_targets(7)] for
        details.

targets::
        The targets definitions. See link:rbm_targets.html[rbm_targets(7)]
        for details.

copy_files::
        A list of files that should be copied when building the package.
        Path is relative to the project's template directory.

input_files::
        Configuration for external input files. See
        link:rbm_input_files.html[rbm_input_files(7)] for details.

input_files_by_name::
        This option contains an hash of all the +input_files+ filenames,
        with their +name+ as index. The input files without a +name+
        are not in this hash.

input_files_id::
        The value of this option is an identifier of the input_files.
        When any of the input files is changed, the identifier changes.
        This identifier is something that can be used in a project's
        filename to trigger a rebuild when any of its input files is
        changed. This identifier is based on: the +input_file_id+ option
        of an input file if it is present, the +filename+ for an input
        file of type +project+, the value of +exec+ for an input file
        of type +exec+, and the +filename+ and the sha256sum of the file
        for any other type of input file. In the case of an input file
        of type +exec+, the value of +exec+ is computed with +getting_id+
        set to true.

input_files_paths::
        The value of this option is an array of all the paths of input
        files that currently exist and are used in the build of the
        current project and its dependencies. This is useful when
        cleaning old build files, to find which ones are still used.

link_input_files::
        When building a project, input files are collected in a
        temporary directory. If this option is set to 1, we try to use
        hard links instead of copies. You should only enable this if
        you don't modify the input files during the build, or if you
        are using +remote_exec+ (in which case the temporary directory
        is only used to copy files to the remote). This option is
        disabled by default, unless +remote_exec+ is used.

timestamp::
        This is the UNIX timestamp, set as modification time on files
        created such as the sources tarball. The default is to use the
        commit time of the commit used. If set to 0 it will use the
        current time.

notmpl::
        An array containing a list of options that should not be
        processed as template (see the +template+ section below for
        details).

step::
        The value of this option is the name of the build script we are
        going to be running (by default 'build', but you could have an
        other one for publishing your build, or for different types of
        packaging). This option should be used read only. If you want
        to change it, use the --step command line option, or the
        +pkg_type+ option.

steps::
        The steps definitions. See link:rbm_steps.html[rbm_steps(7)]
        for details.

build::
        This is the content of the build script used by the +build+
        command. The default is to include the template file named
        +build+.

include::options_misc.asc[]

In addition to the configuration options listed here, you are free to
add any other options that you want, and use them in the template files.
Unfortunately this also means that you won't have an error message in
case of typo in an option name.

WRITTING CONFIGURATION IN PERL
------------------------------

The configuration is in YAML, but you can also use the perl syntax to
set some configuration options. A YAML file can contain multiple
documents, separated by a line with tree dashes ('---'). When reading
a configuration file, rbm will read all documents contained in the
file, and for each of them will :

 - if the document is a hash, use it as configuration

 - if the document is a string, evaluate it as perl, and get the return
   value as as hash containing configuration

If multpiple documents define the same options, the value from the last
one override the values from previous documents.

A configuration file that includes perl code will look like this :
----------------------------
option_1: value 1
option_2: value 2
option_3: value 3
--- |
 (
      option_4 => "value 4",
      option_5 => "value 5",
 )
----------------------------

In this example, 'option_4' and 'option_5' and defined using perl syntax.
Note that the perl code block needs to be indented with at least one space.

An interesting benefit of writting options in perl is that you can
define some options using a perl function reference. If the value of an
option is a function reference, then when that option is looked up the
function will be executed, and the value of the option will be the
return value of the function. The function will receive as parameters
the project's name, an options array reference, and the option that is
queried.

An option defined using a perl function will look like this :
----------------------------
option_1: value 1
--- |
 (
    option_2 => "value 2",
    option_3 => sub {
        my ($project, @option) = @_;
        return "value 3";
    },
 )
----------------------------


SEE ALSO
--------
link:rbm.html[rbm(1)],
link:rbm_targets.html[rbm_targets(7)],
link:rbm_templates.html[rbm_templates(7)]
